<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GimpPlugIn: GIMP 3 Library Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GIMP 3 Library Reference Manual">
<link rel="up" href="libgimp-general.html" title="Functions not Related to Specific Images">
<link rel="prev" href="libgimp3-gimpmessage.html" title="gimpmessage">
<link rel="next" href="GimpPDB.html" title="GimpPDB">
<meta name="generator" content="GTK-Doc V1.33.0 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
                  <a href="#GimpPlugIn.description" class="shortcut">Description</a></span><span id="nav_hierarchy">  <span class="dim">|</span> 
                  <a href="#GimpPlugIn.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties">  <span class="dim">|</span> 
                  <a href="#GimpPlugIn.properties" class="shortcut">Properties</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="libgimp-general.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libgimp3-gimpmessage.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="GimpPDB.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="GimpPlugIn"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="GimpPlugIn.top_of_page"></a>GimpPlugIn</span></h2>
<p>GimpPlugIn — The base class for plug-ins to derive from</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="GimpPlugIn.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_proto_type">
<col class="functions_proto_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-set-translation-domain" title="gimp_plug_in_set_translation_domain ()">gimp_plug_in_set_translation_domain</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-set-help-domain" title="gimp_plug_in_set_help_domain ()">gimp_plug_in_set_help_domain</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-add-menu-branch" title="gimp_plug_in_add_menu_branch ()">gimp_plug_in_add_menu_branch</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-add-temp-procedure" title="gimp_plug_in_add_temp_procedure ()">gimp_plug_in_add_temp_procedure</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-remove-temp-procedure" title="gimp_plug_in_remove_temp_procedure ()">gimp_plug_in_remove_temp_procedure</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">GList</span> *
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-get-temp-procedures" title="gimp_plug_in_get_temp_procedures ()">gimp_plug_in_get_temp_procedures</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="returnvalue">GimpProcedure</span></a> *
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-get-temp-procedure" title="gimp_plug_in_get_temp_procedure ()">gimp_plug_in_get_temp_procedure</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-enable" title="gimp_plug_in_extension_enable ()">gimp_plug_in_extension_enable</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-process" title="gimp_plug_in_extension_process ()">gimp_plug_in_extension_process</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-set-pdb-error-handler" title="gimp_plug_in_set_pdb_error_handler ()">gimp_plug_in_set_pdb_error_handler</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a href="../html/libgimpbase3-gimpbaseenums.html#GimpPDBErrorHandler"><span class="returnvalue">GimpPDBErrorHandler</span></a>
</td>
<td class="function_name">
<a class="link" href="GimpPlugIn.html#gimp-plug-in-get-pdb-error-handler" title="gimp_plug_in_get_pdb_error_handler ()">gimp_plug_in_get_pdb_error_handler</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="GimpPlugIn.properties"></a><h2>Properties</h2>
<div class="informaltable"><table class="informaltable" border="0">
<colgroup>
<col width="150px" class="properties_type">
<col width="300px" class="properties_name">
<col width="200px" class="properties_flags">
</colgroup>
<tbody>
<tr>
<td class="property_type">
<span class="type">GIOChannel</span> *</td>
<td class="property_name"><a class="link" href="GimpPlugIn.html#GimpPlugIn--read-channel" title="The “read-channel” property">read-channel</a></td>
<td class="property_flags">Read / Write / Construct Only</td>
</tr>
<tr>
<td class="property_type">
<span class="type">GIOChannel</span> *</td>
<td class="property_name"><a class="link" href="GimpPlugIn.html#GimpPlugIn--write-channel" title="The “write-channel” property">write-channel</a></td>
<td class="property_flags">Read / Write / Construct Only</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="GimpPlugIn.other"></a><h2>Types and Values</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="other_proto_type">
<col class="other_proto_name">
</colgroup>
<tbody>
<tr>
<td class="datatype_keyword"> </td>
<td class="function_name"><a class="link" href="GimpPlugIn.html#GimpPlugIn-struct" title="GimpPlugIn">GimpPlugIn</a></td>
</tr>
<tr>
<td class="datatype_keyword">struct</td>
<td class="function_name"><a class="link" href="GimpPlugIn.html#GimpPlugInClass" title="struct GimpPlugInClass">GimpPlugInClass</a></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="GimpPlugIn.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="screen">    GObject
    <span class="lineart">╰──</span> GimpPlugIn
</pre>
</div>
<div class="refsect1">
<a name="GimpPlugIn.description"></a><h2>Description</h2>
<p>The base class for plug-ins to derive from. <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> manages the
plug-in's <a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> objects. The procedures a plug-in
implements are registered with GIMP by returning a <span class="type">GList</span> of their
names from either <a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> or
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a>.</p>
<p>Every GIMP plug-in has to implement a <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> subclass and make
it known to the libgimp infrastructure and the main GIMP
application by passing its <span class="type">GType</span> to <a class="link" href="libgimp3-Gimp.html#GIMP-MAIN:CAPS" title="GIMP_MAIN()"><code class="function">GIMP_MAIN()</code></a>.</p>
<p>GIMP_MAIN() passes the 'argc' and 'argv' of the platform's <code class="function">main()</code>
function, along with the <span class="type">GType</span>, to <a class="link" href="libgimp3-Gimp.html#gimp-main" title="gimp_main ()"><code class="function">gimp_main()</code></a>, which creates an
instance of the plug-in's <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> subclass and calls its
virtual functions, depending on how the plug-in was called by GIMP.</p>
<p>There are three different ways GIMP calls a plug-in, "query",
"init" and "run".</p>
<p>The plug-in is called in "query" mode once after it was installed,
or when the cached plug-in information in the config file
"pluginrc" needs to be recreated. In "query" mode,
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> is called and returns a <span class="type">GList</span>
of procedure names the plug-in implements. This is the "normal"
place to register procedures, because the existence of most
procedures doesn't depend on things that change between GIMP
sessions.</p>
<p>The plug-in is called in "init" mode at each GIMP startup, and
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> is called and returns a <span class="type">GList</span>
of procedure names this plug-in implements. This only happens if
the plug-in actually implements
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a>. A plug-in only needs to
implement <a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> if the existence of
its procedures can change between GIMP sessions, for example if
they depend on the presence of external tools, or hardware like
scanners, or online services, or whatever variable circumstances.</p>
<p>In order to register the plug-in's procedures with the main GIMP
application in the plug-in's "query" and "init" modes, <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a>
calls <a class="link" href="GimpPlugIn.html#GimpPlugInClass.create-procedure"><code class="function">GimpPlugInClass.create_procedure()</code></a> on all procedure names in
the exact order of the <span class="type">GList</span> returned by
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> or
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> and then registers the returned
<a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> using <code class="function">GimpProcedureClass.register()</code>.</p>
<p>The plug-in is called in "run" mode whenever one of the procedures
it implements is called by either the main GIMP application or any
other plug-in. In "run" mode, one of the procedure names returned
by <a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> or
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> is passed to
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.create-procedure"><code class="function">GimpPlugInClass.create_procedure()</code></a> which must return a
<a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> for the passed name. The procedure is then executed
by calling <a class="link" href="GimpProcedure.html#gimp-procedure-run" title="gimp_procedure_run ()"><code class="function">gimp_procedure_run()</code></a>.</p>
<p>In any of the three modes, <a class="link" href="GimpPlugIn.html#GimpPlugInClass.quit"><code class="function">GimpPlugInClass.quit()</code></a> is called before
the plug-in process exits, so the plug-in can perform whatever
cleanup necessary.</p>
</div>
<div class="refsect1">
<a name="GimpPlugIn.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="gimp-plug-in-set-translation-domain"></a><h3>gimp_plug_in_set_translation_domain ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_set_translation_domain (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                     <em class="parameter"><code>const <span class="type">gchar</span> *domain_name</code></em>,
                                     <em class="parameter"><code><span class="type">GFile</span> *domain_path</code></em>);</pre>
<p>Sets a textdomain for localisation for the <em class="parameter"><code>plug_in</code></em>
.</p>
<p>This function adds a textdomain to the list of domains Gimp
searches for strings when translating its menu entries. There is no
need to call this function for plug-ins that have their strings
included in the 'gimp-std-plugins' domain as that is used by
default. If the compiled message catalog is not in the standard
location, you may specify an absolute path to another
location.</p>
<p>This function can only be called in the
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> function of a plug-in.</p>
<div class="refsect3">
<a name="gimp-plug-in-set-translation-domain.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>domain_name</p></td>
<td class="parameter_description"><p>The name of the textdomain (must be unique).</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>domain_path</p></td>
<td class="parameter_description"><p>A <span class="type">GFile</span> pointing to the compiled message catalog
(may be <code class="literal">NULL</code>). </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-set-help-domain"></a><h3>gimp_plug_in_set_help_domain ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_set_help_domain (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                              <em class="parameter"><code>const <span class="type">gchar</span> *domain_name</code></em>,
                              <em class="parameter"><code><span class="type">GFile</span> *domain_uri</code></em>);</pre>
<p>Set a help domain and path for the <em class="parameter"><code>plug_in</code></em>
.</p>
<p>This function registers user documentation for the calling plug-in
with the GIMP help system. The domain_uri parameter points to the
root directory where the plug-in help is installed. For each
supported language there should be a file called 'gimp-help.xml'
that maps the help IDs to the actual help files.</p>
<p>This function can only be called in the
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> function of a plug-in.</p>
<div class="refsect3">
<a name="gimp-plug-in-set-help-domain.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>domain_name</p></td>
<td class="parameter_description"><p>The XML namespace of the plug-in's help pages.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>domain_uri</p></td>
<td class="parameter_description"><p>The root URI of the plug-in's help pages.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-add-menu-branch"></a><h3>gimp_plug_in_add_menu_branch ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_add_menu_branch (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                              <em class="parameter"><code>const <span class="type">gchar</span> *menu_path</code></em>,
                              <em class="parameter"><code>const <span class="type">gchar</span> *menu_label</code></em>);</pre>
<p>Add a new sub-menu to the GIMP menus.</p>
<p>This function installs a sub-menu which does not belong to any
procedure at the location <em class="parameter"><code>menu_path</code></em>
.</p>
<p>For translations of <em class="parameter"><code>menu_label</code></em>
 to work properly, <em class="parameter"><code>menu_label</code></em>

should only be marked for translation but passed to this function
untranslated, for example using N_("Submenu"). GIMP will look up
the translation in the textdomain registered for the plug-in.</p>
<p>See also: <a class="link" href="GimpProcedure.html#gimp-procedure-add-menu-path" title="gimp_procedure_add_menu_path ()"><code class="function">gimp_procedure_add_menu_path()</code></a>.</p>
<div class="refsect3">
<a name="gimp-plug-in-add-menu-branch.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>menu_path</p></td>
<td class="parameter_description"><p>The sub-menu's menu path.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>menu_label</p></td>
<td class="parameter_description"><p>The menu label of the sub-menu.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-add-temp-procedure"></a><h3>gimp_plug_in_add_temp_procedure ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_add_temp_procedure (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                 <em class="parameter"><code><a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> *procedure</code></em>);</pre>
<p>This function adds a temporary procedure to <em class="parameter"><code>plug_in</code></em>
. It is usually
called from a <a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-PROC-TYPE-EXTENSION:CAPS"><code class="literal">GIMP_PDB_PROC_TYPE_EXTENSION</code></a> procedure's
<a class="link" href="GimpProcedure.html#GimpProcedureClass.run"><code class="function">GimpProcedureClass.run()</code></a>.</p>
<p>A temporary procedure is a procedure which is only available while
one of your plug-in's "real" procedures is running.</p>
<p>The procedure's type <span class="emphasis"><em>must</em></span> be
<a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-PROC-TYPE-TEMPORARY:CAPS"><code class="literal">GIMP_PDB_PROC_TYPE_TEMPORARY</code></a> or the function will fail.</p>
<p>NOTE: Normally, plug-in communication is triggered by the plug-in
and the GIMP core only responds to the plug-in's requests. You must
explicitly enable receiving of temporary procedure run requests
using either <a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-enable" title="gimp_plug_in_extension_enable ()"><code class="function">gimp_plug_in_extension_enable()</code></a> or
<a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-process" title="gimp_plug_in_extension_process ()"><code class="function">gimp_plug_in_extension_process()</code></a>. See this functions' documentation
for details.</p>
<div class="refsect3">
<a name="gimp-plug-in-add-temp-procedure.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>procedure</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> of type <a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-PROC-TYPE-TEMPORARY:CAPS"><code class="literal">GIMP_PDB_PROC_TYPE_TEMPORARY</code></a>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-remove-temp-procedure"></a><h3>gimp_plug_in_remove_temp_procedure ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_remove_temp_procedure (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                    <em class="parameter"><code>const <span class="type">gchar</span> *procedure_name</code></em>);</pre>
<p>This function removes a temporary procedure from <em class="parameter"><code>plug_in</code></em>
 by the
procedure's <em class="parameter"><code>procedure_name</code></em>
.</p>
<div class="refsect3">
<a name="gimp-plug-in-remove-temp-procedure.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>procedure_name</p></td>
<td class="parameter_description"><p>The name of a <a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> added to <em class="parameter"><code>plug_in</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-get-temp-procedures"></a><h3>gimp_plug_in_get_temp_procedures ()</h3>
<pre class="programlisting"><span class="returnvalue">GList</span> *
gimp_plug_in_get_temp_procedures (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>);</pre>
<p>This function retrieves the list of temporary procedure of <em class="parameter"><code>plug_in</code></em>
 as
added with <a class="link" href="GimpPlugIn.html#gimp-plug-in-add-temp-procedure" title="gimp_plug_in_add_temp_procedure ()"><code class="function">gimp_plug_in_add_temp_procedure()</code></a>.</p>
<div class="refsect3">
<a name="gimp-plug-in-get-temp-procedures.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-plug-in-get-temp-procedures.returns"></a><h4>Returns</h4>
<p>The list of
procedures. </p>
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> GimpProcedure]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-get-temp-procedure"></a><h3>gimp_plug_in_get_temp_procedure ()</h3>
<pre class="programlisting"><a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="returnvalue">GimpProcedure</span></a> *
gimp_plug_in_get_temp_procedure (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                 <em class="parameter"><code>const <span class="type">gchar</span> *procedure_name</code></em>);</pre>
<p>This function retrieves a temporary procedure from <em class="parameter"><code>plug_in</code></em>
 by the
procedure's <em class="parameter"><code>procedure_name</code></em>
.</p>
<div class="refsect3">
<a name="gimp-plug-in-get-temp-procedure.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>procedure_name</p></td>
<td class="parameter_description"><p>The name of a <a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> added to <em class="parameter"><code>plug_in</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-plug-in-get-temp-procedure.returns"></a><h4>Returns</h4>
<p>The procedure if registered, or <code class="literal">NULL</code>. </p>
<p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-extension-enable"></a><h3>gimp_plug_in_extension_enable ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_extension_enable (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>);</pre>
<p>Enables asynchronous processing of messages from the main GIMP
application.</p>
<p>Normally, a plug-in is not called by GIMP except for the call to
the procedure it implements. All subsequent communication is
triggered by the plug-in and all messages sent from GIMP to the
plug-in are just answers to requests the plug-in made.</p>
<p>If the plug-in however registered temporary procedures using
<a class="link" href="GimpPlugIn.html#gimp-plug-in-add-temp-procedure" title="gimp_plug_in_add_temp_procedure ()"><code class="function">gimp_plug_in_add_temp_procedure()</code></a>, it needs to be able to receive
requests to execute them. Usually this will be done by running
<a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-process" title="gimp_plug_in_extension_process ()"><code class="function">gimp_plug_in_extension_process()</code></a> in an endless loop.</p>
<p>If the plug-in cannot use <a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-process" title="gimp_plug_in_extension_process ()"><code class="function">gimp_plug_in_extension_process()</code></a>, i.e. if
it has a GUI and is hanging around in a <span class="type">GMainLoop</span>, it must call
<a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-enable" title="gimp_plug_in_extension_enable ()"><code class="function">gimp_plug_in_extension_enable()</code></a>.</p>
<p>Note that the plug-in does not need to be a
<a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-PROC-TYPE-EXTENSION:CAPS"><span class="type">GIMP_PDB_PROC_TYPE_EXTENSION</span></a> to register temporary procedures.</p>
<p>See also: <a class="link" href="GimpPlugIn.html#gimp-plug-in-add-temp-procedure" title="gimp_plug_in_add_temp_procedure ()"><code class="function">gimp_plug_in_add_temp_procedure()</code></a>.</p>
<div class="refsect3">
<a name="gimp-plug-in-extension-enable.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-extension-process"></a><h3>gimp_plug_in_extension_process ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_extension_process (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                <em class="parameter"><code><span class="type">guint</span> timeout</code></em>);</pre>
<p>Processes one message sent by GIMP and returns.</p>
<p>Call this function in an endless loop after calling
<a class="link" href="GimpProcedure.html#gimp-procedure-extension-ready" title="gimp_procedure_extension_ready ()"><code class="function">gimp_procedure_extension_ready()</code></a> to process requests for running
temporary procedures.</p>
<p>See <a class="link" href="GimpPlugIn.html#gimp-plug-in-extension-enable" title="gimp_plug_in_extension_enable ()"><code class="function">gimp_plug_in_extension_enable()</code></a> for an asynchronous way of
doing the same if running an endless loop is not an option.</p>
<p>See also: <a class="link" href="GimpPlugIn.html#gimp-plug-in-add-temp-procedure" title="gimp_plug_in_add_temp_procedure ()"><code class="function">gimp_plug_in_add_temp_procedure()</code></a>.</p>
<div class="refsect3">
<a name="gimp-plug-in-extension-process.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>timeout</p></td>
<td class="parameter_description"><p>The timeout (in ms) to use for the <code class="function">select()</code> call.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-set-pdb-error-handler"></a><h3>gimp_plug_in_set_pdb_error_handler ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
gimp_plug_in_set_pdb_error_handler (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>,
                                    <em class="parameter"><code><a href="../html/libgimpbase3-gimpbaseenums.html#GimpPDBErrorHandler"><span class="type">GimpPDBErrorHandler</span></a> handler</code></em>);</pre>
<p>Sets an error handler for procedure calls.</p>
<p>This procedure changes the way that errors in procedure calls are
handled. By default GIMP will raise an error dialog if a procedure
call made by a plug-in fails. Using this procedure the plug-in can
change this behavior. If the error handler is set to
<a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-ERROR-HANDLER-PLUGIN:CAPS"><code class="literal">GIMP_PDB_ERROR_HANDLER_PLUGIN</code></a>, then the plug-in is responsible for
calling <a class="link" href="GimpPDB.html#gimp-pdb-get-last-error" title="gimp_pdb_get_last_error ()"><code class="function">gimp_pdb_get_last_error()</code></a> and handling the error whenever
one if its procedure calls fails. It can do this by displaying the
error message or by forwarding it in its own return values.</p>
<div class="refsect3">
<a name="gimp-plug-in-set-pdb-error-handler.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>handler</p></td>
<td class="parameter_description"><p>Who is responsible for handling procedure call errors.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-plug-in-get-pdb-error-handler"></a><h3>gimp_plug_in_get_pdb_error_handler ()</h3>
<pre class="programlisting"><a href="../html/libgimpbase3-gimpbaseenums.html#GimpPDBErrorHandler"><span class="returnvalue">GimpPDBErrorHandler</span></a>
gimp_plug_in_get_pdb_error_handler (<em class="parameter"><code><a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a> *plug_in</code></em>);</pre>
<p>Retrieves the active error handler for procedure calls.</p>
<p>This procedure retrieves the currently active error handler for
procedure calls made by the calling plug-in. See
<a href="/local/head/share/gtk-doc/html/libgimp/libgimp-gimpplugin.html#gimp-plugin-set-pdb-error-handler"><code class="function">gimp_plugin_set_pdb_error_handler()</code></a> for details.</p>
<div class="refsect3">
<a name="gimp-plug-in-get-pdb-error-handler.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>plug_in</p></td>
<td class="parameter_description"><p>A <a class="link" href="GimpPlugIn.html" title="GimpPlugIn"><span class="type">GimpPlugIn</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-plug-in-get-pdb-error-handler.returns"></a><h4>Returns</h4>
<p> Who is responsible for handling procedure call errors.</p>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
</div>
<div class="refsect1">
<a name="GimpPlugIn.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GimpPlugIn-struct"></a><h3>GimpPlugIn</h3>
<pre class="programlisting">typedef struct _GimpPlugIn GimpPlugIn;</pre>
</div>
<hr>
<div class="refsect2">
<a name="GimpPlugInClass"></a><h3>struct GimpPlugInClass</h3>
<pre class="programlisting">struct GimpPlugInClass {
  GObjectClass  parent_class;

  /**
   * GimpPlugInClass::query_procedures:
   * @plug_in: a #GimpPlugIn.
   *
   * Returns: (element-type gchar*) (transfer full):
   *          the names of the procedures registered by @plug_in.
   **/
  GList          * (* query_procedures) (GimpPlugIn  *plug_in);

  /**
   * GimpPlugInClass::init_procedures:
   * @plug_in: a #GimpPlugIn.
   *
   * Returns: (element-type gchar*) (transfer full):
   *          the names of the procedures registered by @plug_in.
   **/
  GList          * (* init_procedures)  (GimpPlugIn  *plug_in);

  /**
   * GimpPlugInClass::create_procedure:
   * @plug_in:        a #GimpPlugIn.
   * @procedure_name: procedure name.
   *
   * Returns: (transfer full):
   *          the procedure to be registered or executed by @plug_in.
   **/
  GimpProcedure  * (* create_procedure) (GimpPlugIn  *plug_in,
                                         const gchar *procedure_name);

  /**
   * GimpPlugInClass::quit:
   * @plug_in: a #GimpPlugIn.
   **/
  void             (* quit)             (GimpPlugIn  *plug_in);

  /* Padding for future expansion */
};
</pre>
<p>A class which every plug-in should subclass, while overriding
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> and/or
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a>, as well as
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.create-procedure"><code class="function">GimpPlugInClass.create_procedure()</code></a>.</p>
<div class="refsect3">
<a name="GimpPlugInClass.members"></a><h4>Members</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="300px" class="struct_members_name">
<col class="struct_members_description">
<col width="200px" class="struct_members_annotations">
</colgroup>
<tbody>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="GimpPlugInClass.query-procedures"></a>query_procedures</code></em> ()</p></td>
<td class="struct_member_description"><p>This method can be overridden by all plug-ins to
return a newly allocated <span class="type">GList</span> of allocated strings naming the
procedures registered by this plug-in. See documentation of
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> for differences.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="GimpPlugInClass.init-procedures"></a>init_procedures</code></em> ()</p></td>
<td class="struct_member_description"><p>This method can be overridden by all plug-ins to
return a newly allocated <span class="type">GList</span> of allocated strings naming
procedures registered by this plug-in.
It is different from <a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> in that
init happens at every startup, whereas query happens only once in
the life of a plug-in (right after installation or update). Hence
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> typically returns procedures
dependent to runtime conditions (such as the presence of a
third-party tool), whereas <a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a>
would usually return procedures that are always available
unconditionally.
Most of the time, you only want to override
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> and leave
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> untouched.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="GimpPlugInClass.create-procedure"></a>create_procedure</code></em> ()</p></td>
<td class="struct_member_description"><p>This method must be overridden by all plug-ins
and return a newly allocated <a class="link" href="GimpProcedure.html" title="GimpProcedure"><span class="type">GimpProcedure</span></a> named <em class="parameter"><code>name</code></em>
. It will
be called for every <em class="parameter"><code>name</code></em>
as returned by
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> and
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a> so care must be taken to
handle them all.
Upon procedure registration, <a class="link" href="GimpPlugIn.html#GimpPlugInClass.create-procedure"><code class="function">GimpPlugInClass.create_procedure()</code></a>
will be called in the order of the lists returned by
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.query-procedures"><code class="function">GimpPlugInClass.query_procedures()</code></a> and
<a class="link" href="GimpPlugIn.html#GimpPlugInClass.init-procedures"><code class="function">GimpPlugInClass.init_procedures()</code></a></p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="GimpPlugInClass.quit"></a>quit</code></em> ()</p></td>
<td class="struct_member_description"><p>This method can be overridden by a plug-in which needs to
perform some actions upon quitting.</p></td>
<td class="struct_member_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-3-0.html#api-index-3.0">3.0</a></p>
</div>
</div>
<div class="refsect1">
<a name="GimpPlugIn.property-details"></a><h2>Property Details</h2>
<div class="refsect2">
<a name="GimpPlugIn--read-channel"></a><h3>The <code class="literal">“read-channel”</code> property</h3>
<pre class="programlisting">  “read-channel”             <span class="type">GIOChannel</span> *</pre>
<p>The GIOChanel to read from GIMP.</p>
<p>Owner: GimpPlugIn</p>
<p>Flags: Read / Write / Construct Only</p>
</div>
<hr>
<div class="refsect2">
<a name="GimpPlugIn--write-channel"></a><h3>The <code class="literal">“write-channel”</code> property</h3>
<pre class="programlisting">  “write-channel”            <span class="type">GIOChannel</span> *</pre>
<p>The GIOChanel to write to GIMP.</p>
<p>Owner: GimpPlugIn</p>
<p>Flags: Read / Write / Construct Only</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.0</div>
</body>
</html>